Inside Macintosh: Imaging with QuickDraw
In quest of faster execution time, some applications directly modify ColorTable , PixPat , GrafPort , CGrafPort , or GDevice records rather than using the routines provided for that purpose. Direct manipulation of the fields of these records can cause problems now, and may cause additional problems as QuickDraw continues to evolve.
For example, the Color Manager (described in the chapter "Color Manager" in Inside Macintosh: Advanced Color Imaging ) maintains an inverse table for every color table with which it works in order to speed up the process of searching the color table. If your application directly changes an entry in the color table, the Color Manager doesn't know that its inverse table no longer works correctly.
However, by using the routines CTabChanged , PixPatChanged , PortChanged , and GDeviceChanged , you can lessen the adverse effects of directly modifying the fields of ColorTable , PixPat , GrafPort , CGrafPort , and GDevice records. For example, should you directly change the field of a ColorTable record and then call the CTabChanged procedure, it invalidates the ctSeed field of the ColorTable record, which signals the Color Manager that the table has been changed and its inverse table needs to be rebuilt.
If you modify the content of a ColorTable record (described on ColorTable ), use the CTabChanged procedure.
PROCEDURE CTabChanged (ctab: CTabHandle);
For the ColorTable record you specify in the ctab parameter, the CTabChanged procedure calls the Color Manager function GetCTSeed to get a new seed (that is, a new, unique identifier in the ctSeed field of the ColorTable record) and notifies Color QuickDraw of the change.
The CTabChanged procedure may move or purge memory in the application heap. Your application should not call the CTabChanged procedure at interrupt time.
Your application should never need to directly modify a ColorTable record and use the CTabChanged procedure; instead, your application should use the QuickDraw routines described in this book for manipulating the values in a ColorTable record.
If you modify the content of a PixPat record (described on PixPat ), including its PixMap record or the image in its patData field, use the PixPatChanged procedure.
PROCEDURE PixPatChanged (ppat: PixPatHandle);
The PixPatChanged procedure sets the patXValid field of the PixPat record specified in the ppat parameter to -1 and notifies QuickDraw of the change.
If your application changes the pmTable field of a pixel pattern's PixMap record, it should call PixPatChanged . However, if your application changes the content of the color table referenced by the PixMap record's pmTable field, it should call PixPatChanged and the CTabChanged procedure as well. (The CTabChanged procedure is described in the preceding section.)
The PixPatChanged procedure may move or purge memory in the application heap. Your application should not call the PixPatChanged procedure at interrupt time.
Your application should never need to directly modify a PixPat record and use the PixPatChanged procedure; instead, your application should use the QuickDraw routines described in this book for manipulating the values in a PixPat record.
If you modify the content of a GrafPort record (described in the chapter "Basic QuickDraw" in this book) or CGrafPort record (described on CGrafPort ), including any of the data structures specified by handles within the record, use the PortChanged procedure.
PROCEDURE PortChanged (port: GrafPtr);
The PortChanged procedure notifies QuickDraw that your application has changed the graphics port specified in the port parameter. If your application has changed a CGrafPort record, it must coerce its pointer (that is, its CGrafPtr ) to a pointer to a GrafPort record (that is, to a GrafPtr ) before passing the pointer in the port parameter.
You generally should not directly change any of the PixPat records specified in a CGrafPort record, but instead use the PenPixPat and BackPixPat procedures. However, if your application does change the content of a PixPat record, it should call the PixPatChanged procedure (described in the preceding section) as well as the PortChanged procedure.
If your application changes the pmTable field of the PixMap record specified in the graphics port, your application should call PortChanged . If your application changes the content of the ColorTable record referenced by the pmTable field, it should call CTabChanged as well.
If you modify the content of a GDevice record (described in the chapter "Graphics Devices" in this book), use the GDeviceChanged procedure.
PROCEDURE GDeviceChanged (gdh: GDHandle);
The GDeviceChanged procedure notifies Color QuickDraw that your application has changed the GDevice record specified in the gdh parameter.
If your application changes the pmTable field of the PixMap record specified in a GDevice record, your application should call GDeviceChanged . If your application changes the content of the ColorTable record referenced by the PixMap record, it should call GDeviceChanged and CTabChanged as well.
The GDeviceChanged procedure may move or purge memory in the application heap. Your application should not call the GDeviceChanged procedure at interrupt time.
Your application should never need to directly modify a GDevice record and use the GDeviceChanged procedure; instead, your application should use the QuickDraw routines described in this book for manipulating the values in a GDevice record.